home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / OpenDoc Development / Debugging Support / OpenDoc™ Source Code / Storage / Bento / CM / Handlers.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-08-28  |  10.5 KB  |  206 lines  |  [TEXT/MPS ]
  1. /*
  2.     File:        Handlers.h
  3.  
  4.     Contains:    Container Manager Handlers Interfaces
  5.  
  6.     Written by:    Ira L. Ruben
  7.  
  8.     Owned by:    Ed Lai
  9.  
  10.     Copyright:    © 1991-1994 by Apple Computer, Inc., all rights reserved.
  11.  
  12.     Change History (most recent first):
  13.  
  14.          <2>     8/26/94    EL        #1182319 Matches Handlers.c
  15.          <4>      5/9/94    MB        #1162181: Changes necessary to install MMM.
  16.          <3>      2/3/94    EL        Bento File names are now eight chars or
  17.                                     less.
  18.          <2>    11/22/93    EL        Add refcon for alloc and free handers.
  19.  
  20.     To Do:
  21. */
  22.  
  23. /*---------------------------------------------------------------------------*
  24.  |                                                                           |
  25.  |                            <<< Handlers.h >>>                             |
  26.  |                                                                           |
  27.  |                   Container Manager Handlers Interfaces                   |
  28.  |                                                                           |
  29.  |                               Ira L. Ruben                                |
  30.  |                                 11/18/91                                  |
  31.  |                                                                           |
  32.  |                  Copyright Apple Computer, Inc. 1991-1994                 |
  33.  |                           All rights reserved.                            |
  34.  |                                                                           |
  35.  *---------------------------------------------------------------------------*
  36.  
  37.  Containers (files, memory, or whatever) are always access through handlers, to provide
  38.  platform independence.  Handlers are responsible for doing all the I/O operations,
  39.  including opening and closing, to containers.  They are also responsible for reading and
  40.  writing the container label.
  41.  
  42.  The routines defined by this header are the API interfaces to allow the Container Manager
  43.  to determine what handlers it should use for a particular container.  The Container
  44.  Manager handler routines defined here maintain container type name/metahandler
  45.  associations.
  46. */
  47.  
  48. #ifndef __HANDLERS__
  49. #define __HANDLERS__
  50.  
  51. #include <stdio.h>
  52.  
  53. #ifndef __CMTYPES__
  54. #include "CMTypes.h"
  55. #endif
  56. #ifndef __CM_API_TYPES__
  57. #include "CMAPITyp.h"
  58. #endif
  59. #ifndef __SYMMGR__
  60. #include "SymTbMgr.h"      
  61. #endif
  62. #ifndef __SESSIONDATA__
  63. #include "Session.h"          
  64. #endif
  65.  
  66. struct SessionGlobalData;
  67.  
  68.                                                                     CM_CFUNCTIONS
  69.  
  70. /* The metahandler symbol table contains the associations between type names and meta-    */
  71. /* handler routine addresses.                                                                                                                     */
  72.  
  73. struct MetaHandler {                                        /* Layout for a metahandler symbol table entry:    */
  74.     SymbolLinks     theTreeLinks;                        /*         standard right/left links (must be 1st)        */
  75.     CMMetaHandler     metaHandler;                    /*        ptr to the metahandler                                        */
  76.     CM_UCHAR        typeName[1];                            /*        start of type name for this handler                */
  77. };
  78. typedef struct MetaHandler MetaHandler, *MetaHandlerPtr;
  79.  
  80.  
  81. /* The following defines the vector of handler routines which is built as part of every    */
  82. /* container control block.    The vector is filled in when a container is opened by                */
  83. /* calling a metahandler proc which returns the handler addresses.                                            */
  84.  
  85. struct HandlerOps {                                            /* Basic I/O operations and their prototypes        */
  86.     CMRefCon (*cmfopen)(CMRefCon attributes, CMOpenMode mode);    
  87.     void (*cmfclose)(CMRefCon refCon);
  88.     CMSize (*cmfflush)(CMRefCon refCon);
  89.     CMSize (*cmfseek)(CMRefCon refCon, CM_LONG posOff, CMSeekMode mode);
  90.     CMSize (*cmftell)(CMRefCon refCon);
  91.     CMSize (*cmfread)(CMRefCon refCon, CMPtr buffer,  CMSize elementSize, CMCount theCount);
  92.     CMSize (*cmfwrite)(CMRefCon refCon, CMPtr buffer, CMSize elementSize, CMCount theCount);
  93.     CMEofStatus (*cmfeof)(CMRefCon refCon);
  94.     CMBoolean (*cmftrunc)(CMRefCon refCon, CMSize containerSize);
  95.     CMSize (*cmgetContainerSize)(CMRefCon refCon);
  96.     void (*cmreadLabel)(CMRefCon refCon, CMMagicBytes magicByteSequence, CMContainerFlags *flags,
  97.                                           CM_USHORT *bufSize, CM_USHORT *majorVersion, CM_USHORT *minorVersion,
  98.                                           CMSize *tocOffset, CMSize *tocSize);
  99.     void (*cmwriteLabel)(CMRefCon refCon, CMMagicBytes magicByteSequence, CMContainerFlags flags,
  100.                                            CM_USHORT bufSize, CM_USHORT majorVersion, CM_USHORT minorVersion,
  101.                                               CMSize tocOffset, CMSize tocSize);
  102.     CMValue (*cmreturnParentValue)(CMRefCon refCon);
  103.     char *(*cmreturnContainerName)(CMRefCon refCon);
  104.     CMType (*cmreturnTargetType)(CMRefCon refCon, CMContainer container);
  105.     void (*cmextractData)(CMRefCon refCon, CMDataBuffer updateBuffer, CMSize size,
  106.                                                 CMPrivateData data);
  107.     void (*cmformatData)(CMRefCon refCon, CMDataBuffer updateBuffer, CMSize size,
  108.                                              CMPrivateData data);
  109. };
  110. typedef struct HandlerOps HandlerOps;
  111.  
  112.  
  113. /* To make it easier and more readable for the Container Manager to call the handlers,    */
  114. /* the following macros are defined.  The "refCon" is located in the container control     */
  115. /* block.     Note the container is always an explicit parameter to these macros since in    */
  116. /* some places we may be dealing with more than one container due to updating.                    */
  117.  
  118. #define CMfopen(container, refCon, m)           (*((ContainerPtr)container)->handler.cmfopen)((void *)refCon, (CMOpenMode)(m))
  119. #define CMfclose(container)                                 (*((ContainerPtr)container)->handler.cmfclose)(((ContainerPtr)container)->refCon)
  120. #define CMfflush(container)                                 (*((ContainerPtr)container)->handler.cmfflush)(((ContainerPtr)container)->refCon)
  121. #define CMfseek(container, p, m)                         (*((ContainerPtr)container)->handler.cmfseek)(((ContainerPtr)container)->refCon, (CM_LONG)(p), (CMSeekMode)(m))
  122. #define CMftell(container)                                     (*((ContainerPtr)container)->handler.cmftell)(((ContainerPtr)container)->refCon)
  123. #define CMfread(container, b, e, c)                  (*((ContainerPtr)container)->handler.cmfread)(((ContainerPtr)container)->refCon, (CMPtr)(b), (CMSize)(e), (CMCount)(c))
  124. #define CMfwrite(container, b, e, c)                 (*((ContainerPtr)container)->handler.cmfwrite)(((ContainerPtr)container)->refCon, (CMPtr)(b), (CMSize)(e), (CMCount)(c))
  125. #define CMfeof(container)                                     (*((ContainerPtr)container)->handler.cmfeof)(((ContainerPtr)container)->refCon)
  126. #define CMftrunc(container, s)                            (*((ContainerPtr)container)->handler.cmftrunc)(((ContainerPtr)container)->refCon, (CMSize)(s))
  127. #define CMgetContainerSize(container)                (*((ContainerPtr)container)->handler.cmgetContainerSize)(((ContainerPtr)container)->refCon)
  128. #define CMreadLabel(container, m, f, n, v1, v2, t, l)  (*((ContainerPtr)container)->handler.cmreadLabel)(((ContainerPtr)container)->refCon, (CMMagicBytes)(m), (CMContainerFlags*)(f), (CM_USHORT*)(n), (CM_USHORT*)(v1), (CM_USHORT*)(v2), (CMSize*)(t), (CMSize*)(l))
  129. #define CMwriteLabel(container, m, f, n, v1, v2, t, l) (*((ContainerPtr)container)->handler.cmwriteLabel)(((ContainerPtr)container)->refCon, (CMMagicBytes)(m), (CMContainerFlags)(f), (CM_USHORT)(n), (CM_USHORT)(v1), (CM_USHORT)(v2), (CMSize)(t), (CMSize)(l))
  130. #define CMreturnParentValue(container)            (TOCValueHdrPtr)(*((ContainerPtr)container)->handler.cmreturnParentValue)(((ContainerPtr)container)->refCon)
  131. #define CMreturnContainerName(container)        (*((ContainerPtr)container)->handler.cmreturnContainerName)(((ContainerPtr)container)->refCon)
  132. #define CMreturnTargeType(container)                (*((ContainerPtr)container)->handler.cmreturnTargetType)(((ContainerPtr)container)->refCon, (CMContainer)container)
  133. #define CMextractData(container, b, n, d)         (*((ContainerPtr)container)->handler.cmextractData)(((ContainerPtr)container)->refCon, (CMDataBuffer)(b), (CMSize)(n), (CMPrivateData)(d))
  134. #define CMformatData(container, b, n, d)         (*((ContainerPtr)container)->handler.cmformatData)(((ContainerPtr)container)->refCon, (CMDataBuffer)(b), (CMSize)(n), (CMPrivateData)(d))
  135.  
  136. /* Sorry about the length of these lines.  The casts make them that way.  That is done    */
  137. /* because some of the Container Manager routines that use these pass values coming in    */
  138. /* from external (i.e., "CM...") calls.  The external types are generic and have to be    */
  139. /* converted to the "real thing" (if you know what I mean).                                                            */
  140.  
  141. /* NOTE: Currently CMfeof() is NOT used by the container manager...                                            */
  142.  
  143.  
  144. /* Just like the container specific handlers, we have macros for calling the memory         */
  145. /* management handlers.  These all use the session data pointer via the current                 */
  146. /* container whose pointer is assumed to be the variable name "container".                             */
  147.  
  148. #define CMmalloc(size)                         (*(SESSION->cmMalloc))((CMSize)size,SESSION->refCon)
  149. #define CMfree(ptr)                                 (*(SESSION->cmFree))((CMPtr)ptr,SESSION->refCon)
  150.  
  151.  
  152. MetaHandlerPtr cmDefineMetaHandler(CMMetaHandler metaHandler, 
  153.                                                                       const CM_UCHAR *typeName,
  154.                                                                         CMBoolean *dup,
  155.                                                                      struct SessionGlobalData *sessionData);
  156.     /*
  157.   Define a new metahandler with the specifed type (a C string). The function returns a
  158.   pointer to the new handler or, if dup is true, a pointer to a previously defined entry.
  159.     
  160.     If NULL is returned then there was an allocation failure and the new type could not be
  161.     created.
  162.     
  163.     Note, the global data session pointer created by CMStartSession() is passed since
  164.     methandlers are global to all containers and thus the root of the metahandler symbol
  165.     table is kept as part of the session data.
  166.     */
  167.  
  168.  
  169. MetaHandlerPtr cmLookupMetaHandler(const CM_UCHAR *typeName,
  170.                                                                      struct SessionGlobalData *sessionData);
  171.     /*
  172.     Find a metahandler associated with the specified type.  If found, the HandlerPtr to the 
  173.     found entry is returned (which includes the handler proc and type).  If not found NULL
  174.     is returned.
  175.     
  176.     Note, we allocate a temporary handler table entry here and then free it.   If the
  177.     allocation fails, SessionSuccess, a session status switch, is returned false.  Otherwise
  178.     SessionSuccess is true.
  179.     
  180.     The global data session pointer created by CMStartSession() is passed since methandlers
  181.     are global to all containers and thus the root of the metahandler symbol table is kept
  182.     as part of the session data.
  183.     */
  184.     
  185.  
  186. void cmForEachMetaHandler(CMRefCon refCon, 
  187.                                                     void (*action)(MetaHandlerPtr aHandler, CMRefCon refCon),
  188.                                                     struct SessionGlobalData *sessionData);    
  189.     /*
  190.     Do (call) the specified action for each defined metahandler in the current session. The
  191.     pointer to each metahandler entry is passed to the action routine along with a "refCon"
  192.     which the caller can use as a communication facility to convey additional info to the
  193.     action routine.
  194.     */
  195.  
  196.  
  197. void cmFreeAllMetaHandlers(struct SessionGlobalData *sessionData);
  198.     /*
  199.   This routine is called to remove the definitions of ALL previously defined metahandlers
  200.   for the current session.
  201.     */
  202.     
  203.  
  204.                                                           CM_END_CFUNCTIONS
  205. #endif
  206.